Move documentation to inline comments: GtkUIManager
authorJavier Jardón <jjardon@gnome.org>
Mon, 18 Apr 2011 17:53:30 +0000 (18:53 +0100)
committerJavier Jardón <jjardon@gnome.org>
Mon, 18 Apr 2011 17:55:34 +0000 (18:55 +0100)
docs/reference/gtk/tmpl/.gitignore
docs/reference/gtk/tmpl/gtkuimanager.sgml [deleted file]
gtk/gtkuimanager.c
gtk/gtkuimanager.h

index 997eb9e0f63478aa25ab6f74278342e58cec1235..ac14a49130dec38f258feea46df32e432fe83de2 100644 (file)
@@ -140,5 +140,6 @@ gtktreestore.sgml
 gtktreeview.sgml
 gtktreeviewcolumn.sgml
 gtktypeutils.sgml
+gtkuimanager.sgml
 gtkwindow.sgml
 gtkwindowgroup.sgml
diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml
deleted file mode 100644 (file)
index 721e444..0000000
+++ /dev/null
@@ -1,508 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkUIManager
-
-<!-- ##### SECTION Short_Description ##### -->
-Constructing menus and toolbars from an XML description
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkUIManager constructs a user interface (menus and toolbars) from
-one or more UI definitions, which reference actions from one or more 
-action groups. 
-</para>
-<refsect2 id="XML-UI"><title>UI Definitions</title>
-<para>
-The UI definitions are specified in an XML format which can be
-roughly described by the following DTD. 
-</para>
-<para>
-Do not confuse the GtkUIManager UI Definitions described here with
-the similarly named <link linkend="BUILDER-UI">GtkBuilder UI 
-Definitions</link>. 
-</para>
-<para>
-<programlisting><![CDATA[
-<!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
-<!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
-<!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
-<!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
-<!ELEMENT toolbar     (toolitem|separator|placeholder)* >
-<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
-<!ELEMENT menuitem     EMPTY >
-<!ELEMENT toolitem     (menu?) >
-<!ELEMENT separator    EMPTY >
-<!ELEMENT accelerator  EMPTY >
-<!ATTLIST menubar      name                      &num;IMPLIED 
-                       action                    &num;IMPLIED >
-<!ATTLIST toolbar      name                      &num;IMPLIED 
-                       action                    &num;IMPLIED >
-<!ATTLIST popup        name                      &num;IMPLIED 
-                       action                    &num;IMPLIED 
-                       accelerators (true|false) &num;IMPLIED >
-<!ATTLIST placeholder  name                      &num;IMPLIED
-                       action                    &num;IMPLIED >
-<!ATTLIST separator    name                      &num;IMPLIED
-                       action                    &num;IMPLIED
-                       expand       (true|false) &num;IMPLIED >
-<!ATTLIST menu         name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED >
-<!ATTLIST menuitem     name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED
-                       always-show-image (true|false) &num;IMPLIED >
-<!ATTLIST toolitem     name                      &num;IMPLIED
-                       action                    &num;REQUIRED
-                       position     (top|bot)    &num;IMPLIED >
-<!ATTLIST accelerator  name                      &num;IMPLIED
-                       action                    &num;REQUIRED >
-]]></programlisting>
-There are some additional restrictions beyond those specified in the
-DTD, e.g. every toolitem must have a toolbar in its anchestry and
-every menuitem must have a menubar or popup in its anchestry. Since
-a #GMarkup parser is used to parse the UI description, it must not only
-be valid XML, but valid #GMarkup. 
-</para>
-<para>
-If a name is not specified, it defaults to the action. If an action is 
-not specified either, the element name is used. The name and action 
-attributes must not contain '/' characters after parsing (since that 
-would mess up path lookup) and must be usable as XML attributes when 
-enclosed in doublequotes, thus they must not '"' characters or references 
-to the &amp;quot; entity.
-</para>
-<example>
-<title>A UI definition</title>
-<programlisting>
-&lt;ui&gt;
-  &lt;menubar&gt;
-    &lt;menu name="FileMenu" action="FileMenuAction"&gt;
-      &lt;menuitem name="New" action="New2Action" /&gt;
-      &lt;placeholder name="FileMenuAdditions" /&gt;
-    &lt;/menu&gt;
-    &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
-      &lt;menuitem name="Left" action="justify-left"/&gt;
-      &lt;menuitem name="Centre" action="justify-center"/&gt;
-      &lt;menuitem name="Right" action="justify-right"/&gt;
-      &lt;menuitem name="Fill" action="justify-fill"/&gt;
-    &lt;/menu&gt;
-  &lt;/menubar&gt;
-  &lt;toolbar action="toolbar1"&gt;
-    &lt;placeholder name="JustifyToolItems"&gt;
-      &lt;separator/&gt;
-      &lt;toolitem name="Left" action="justify-left"/&gt;
-      &lt;toolitem name="Centre" action="justify-center"/&gt;
-      &lt;toolitem name="Right" action="justify-right"/&gt;
-      &lt;toolitem name="Fill" action="justify-fill"/&gt;
-      &lt;separator/&gt;
-    &lt;/placeholder&gt;
-  &lt;/toolbar&gt;
-&lt;/ui&gt;
-</programlisting>
-</example>
-<para>
-The constructed widget hierarchy is very similar to the element tree
-of the XML, with the exception that placeholders are merged into their
-parents. The correspondence of XML elements to widgets should be
-almost obvious: 
-<variablelist>
-<varlistentry><term>menubar</term>
-<listitem><para>a #GtkMenuBar</para></listitem>
-</varlistentry>
-<varlistentry><term>toolbar</term>
-<listitem><para>a #GtkToolbar</para></listitem>
-</varlistentry>
-<varlistentry><term>popup</term>
-<listitem><para>a toplevel #GtkMenu</para></listitem>
-</varlistentry>
-<varlistentry><term>menu</term>
-<listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
-</varlistentry>
-<varlistentry><term>menuitem</term>
-<listitem><para>a #GtkMenuItem subclass, the exact type depends on the
-action</para></listitem> 
-</varlistentry>
-<varlistentry><term>toolitem</term>
-<listitem><para>a #GtkToolItem subclass, the exact type depends on the
-action. Note that toolitem elements may contain a menu element, but only
-if their associated action specifies a #GtkMenuToolButton as proxy.</para></listitem> 
-</varlistentry>
-<varlistentry><term>separator</term>
-<listitem><para>a #GtkSeparatorMenuItem or
-#GtkSeparatorToolItem</para></listitem> 
-</varlistentry>
-<varlistentry><term>accelerator</term>
-<listitem><para>a keyboard accelerator</para></listitem> 
-</varlistentry>
-</variablelist>
-</para>
-<para>
-The "position" attribute determines where a constructed widget is positioned
-wrt. to its siblings in the partially constructed tree. If it is
-"top", the widget is prepended, otherwise it is appended.
-</para>
-</refsect2>
-<refsect2 id="UI-Merging">
-<title>UI Merging</title>
-<para>
-The most remarkable feature of #GtkUIManager is that it can overlay a set
-of menuitems and toolitems over another one, and demerge them later.
-</para>
-<para>
-Merging is done based on the names of the XML elements. Each element is 
-identified by a path which consists of the names of its anchestors, separated
-by slashes. For example, the menuitem named "Left" in the example above
-has the path <literal>/ui/menubar/JustifyMenu/Left</literal> and the
-toolitem with the same name has path 
-<literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
-</para>
-</refsect2>
-<refsect2>
-<title>Accelerators</title>
-<para>
-Every action has an accelerator path. Accelerators are installed together with
-menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
-elements in the UI definition. This makes it possible to have accelerators for
-actions even if they have no visible proxies.
-</para>
-</refsect2>
-<refsect2 id="Smart-Separators">
-<title>Smart Separators</title>
-<para>
-The separators created by #GtkUIManager are "smart", i.e. they do not show up 
-in the UI unless they end up between two visible menu or tool items. Separators
-which are located at the very beginning or end of the menu or toolbar 
-containing them, or multiple separators next to each other, are hidden. This 
-is a useful feature, since the merging of UI elements from multiple sources 
-can make it hard or impossible to determine in advance whether a separator 
-will end up in such an unfortunate position.
-</para>
-
-<para>
-For separators in toolbars, you can set <literal>expand="true"</literal> to
-turn them from a small, visible separator to an expanding, invisible one.
-Toolitems following an expanding separator are effectively right-aligned.
-</para>
-</refsect2>
-<refsect2>
-<title>Empty Menus</title>
-<para>
-Submenus pose similar problems to separators inconnection with merging. It is 
-impossible to know in advance whether they will end up empty after merging. 
-#GtkUIManager offers two ways to treat empty submenus:
-<itemizedlist>
-<listitem><para>make them disappear by hiding the menu item they're attached to
-</para></listitem>
-<listitem><para>add an insensitive "Empty" item
-</para></listitem>
-</itemizedlist>
-The behaviour is chosen based on the "hide_if_empty" property of the action 
-to which the submenu is associated.
-</para>
-</refsect2>
-
-<refsect2 id="GtkUIManager-BUILDER-UI">
-<title>GtkUIManager as GtkBuildable</title>
-<para>
-The GtkUIManager implementation of the GtkBuildable interface accepts
-GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
-</para>
-<para>
-A GtkUIManager UI definition as described above can be embedded in
-an GtkUIManager &lt;object&gt; element in a GtkBuilder UI definition.
-</para>
-<para>
-The widgets that are constructed by a GtkUIManager can be embedded in
-other parts of the constructed user interface with the help of the
-"constructor" attribute. See the example below.
-</para>
-<example>
-<title>An embedded GtkUIManager UI definition</title>
-<programlisting><![CDATA[
-<object class="GtkUIManager" id="uiman">
-  <child>
-    <object class="GtkActionGroup" id="actiongroup">
-      <child>
-        <object class="GtkAction" id="file">
-          <property name="label">_File</property>
-        </object>
-      </child>
-    </object>
-  </child>
-  <ui>
-    <menubar name="menubar1">
-      <menu action="file">
-      </menu>
-    </menubar>
-  </ui>
-</object>
-<object class="GtkWindow" id="main-window">
-  <child>
-    <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
-  </child>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkBuilder
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkUIManager ##### -->
-<para>
-The <structname>GtkUIManager</structname> struct contains only private
-members and should not be accessed directly.
-</para>
-
-
-<!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-
-<!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::connect-proxy ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::disconnect-proxy ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-@widget: 
-
-<!-- ##### SIGNAL GtkUIManager::post-activate ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkUIManager::pre-activate ##### -->
-<para>
-
-</para>
-
-@uimanager: the object which received the signal.
-@arg1: 
-
-<!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkUIManager:ui ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_ui_manager_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@manager: 
-@add_tearoffs: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@action_group: 
-@pos: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@action_group: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
-<para>
-
-</para>
-
-@manager: 
-@path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_toplevels ##### -->
-<para>
-
-</para>
-
-@manager: 
-@types: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
-<para>
-
-</para>
-
-@manager: 
-@path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
-<para>
-
-</para>
-
-@manager: 
-@buffer: 
-@length: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
-<para>
-
-</para>
-
-@manager: 
-@filename: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### ENUM GtkUIManagerItemType ##### -->
-<para>
-These enumeration values are used by gtk_ui_manager_add_ui() to determine
-what UI element to create.
-</para>
-
-@GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
-@GTK_UI_MANAGER_MENUBAR: Create a menubar.
-@GTK_UI_MANAGER_MENU: Create a menu.
-@GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
-@GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
-@GTK_UI_MANAGER_POPUP: Create a popup menu.
-@GTK_UI_MANAGER_MENUITEM: Create a menuitem.
-@GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
-@GTK_UI_MANAGER_SEPARATOR: Create a separator.
-@GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
-@GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the actions' accelerators are shown.
-
-<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@merge_id: 
-@path: 
-@name: 
-@action: 
-@type: 
-@top: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@merge_id: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
-<para>
-
-</para>
-
-@manager: 
-
-
index e5e536a401061e0958cc8820b4f0139a40ebc7ad..6f1c62598ef16331b74b026c6cf8873a6f56179d 100644 (file)
 #include "gtkwindow.h"
 #include "gtkprivate.h"
 
+
+/**
+ * SECTION:gtkuimanager
+ * @Short_description: Constructing menus and toolbars from an XML description
+ * @Title: GtkUIManager
+ * @See_also:#GtkBuilder
+ *
+ * A #GtkUIManager constructs a user interface (menus and toolbars) from
+ * one or more UI definitions, which reference actions from one or more
+ * action groups.
+ *
+ * <refsect2 id="XML-UI">
+ * <title>UI Definitions</title>
+ * <para>
+ * The UI definitions are specified in an XML format which can be
+ * roughly described by the following DTD.
+ *
+ * <note><para>
+ * Do not confuse the GtkUIManager UI Definitions described here with
+ * the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
+ * Definitions</link>.
+ * </para></note>
+ *
+ * <programlisting>
+ * <![CDATA[
+ * <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
+ * <!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
+ * <!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
+ * <!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
+ * <!ELEMENT toolbar     (toolitem|separator|placeholder)* >
+ * <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
+ * <!ELEMENT menuitem     EMPTY >
+ * <!ELEMENT toolitem     (menu?) >
+ * <!ELEMENT separator    EMPTY >
+ * <!ELEMENT accelerator  EMPTY >
+ * <!ATTLIST menubar      name                      #IMPLIED
+ *                        action                    #IMPLIED >
+ * <!ATTLIST toolbar      name                      #IMPLIED
+ *                        action                    #IMPLIED >
+ * <!ATTLIST popup        name                      #IMPLIED
+ *                        action                    #IMPLIED
+ *                        accelerators (true|false) #IMPLIED >
+ * <!ATTLIST placeholder  name                      #IMPLIED
+ *                        action                    #IMPLIED >
+ * <!ATTLIST separator    name                      #IMPLIED
+ *                        action                    #IMPLIED
+ *                        expand       (true|false) #IMPLIED >
+ * <!ATTLIST menu         name                      #IMPLIED
+ *                        action                    #REQUIRED
+ *                        position     (top|bot)    #IMPLIED >
+ * <!ATTLIST menuitem     name                      #IMPLIED
+ *                        action                    #REQUIRED
+ *                        position     (top|bot)    #IMPLIED
+ *                        always-show-image (true|false) #IMPLIED >
+ * <!ATTLIST toolitem     name                      #IMPLIED
+ *                        action                    #REQUIRED
+ *                        position     (top|bot)    #IMPLIED >
+ * <!ATTLIST accelerator  name                      #IMPLIED
+ *                        action                    #REQUIRED >
+ * ]]>
+ * </programlisting>
+ * There are some additional restrictions beyond those specified in the
+ * DTD, e.g. every toolitem must have a toolbar in its anchestry and
+ * every menuitem must have a menubar or popup in its anchestry. Since
+ * a #GMarkup parser is used to parse the UI description, it must not only
+ * be valid XML, but valid #GMarkup.
+ *
+ * If a name is not specified, it defaults to the action. If an action is
+ * not specified either, the element name is used. The name and action
+ * attributes must not contain '/' characters after parsing (since that
+ * would mess up path lookup) and must be usable as XML attributes when
+ * enclosed in doublequotes, thus they must not '"' characters or references
+ * to the &quot; entity.
+ *
+ * <example>
+ * <title>A UI definition</title>
+ * <programlisting>
+ * <ui>
+ *   <menubar>
+ *     <menu name="FileMenu" action="FileMenuAction">
+ *       <menuitem name="New" action="New2Action" />
+ *       <placeholder name="FileMenuAdditions" />
+ *     </menu>
+ *     <menu name="JustifyMenu" action="JustifyMenuAction">
+ *       <menuitem name="Left" action="justify-left"/>
+ *       <menuitem name="Centre" action="justify-center"/>
+ *       <menuitem name="Right" action="justify-right"/>
+ *       <menuitem name="Fill" action="justify-fill"/>
+ *     </menu>
+ *   </menubar>
+ *   <toolbar action="toolbar1">
+ *     <placeholder name="JustifyToolItems">
+ *       <separator/>
+ *       <toolitem name="Left" action="justify-left"/>
+ *       <toolitem name="Centre" action="justify-center"/>
+ *       <toolitem name="Right" action="justify-right"/>
+ *       <toolitem name="Fill" action="justify-fill"/>
+ *       <separator/>
+ *     </placeholder>
+ *   </toolbar>
+ * </ui>
+ * </programlisting>
+ * </example>
+ *
+ * The constructed widget hierarchy is very similar to the element tree
+ * of the XML, with the exception that placeholders are merged into their
+ * parents. The correspondence of XML elements to widgets should be
+ * almost obvious:
+ * <variablelist>
+ * <varlistentry>
+ * <term>menubar</term>
+ * <listitem><para>a #GtkMenuBar</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>toolbar</term>
+ * <listitem><para>a #GtkToolbar</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>popup</term>
+ * <listitem><para>a toplevel #GtkMenu</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>menu</term>
+ * <listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>menuitem</term>
+ * <listitem><para>a #GtkMenuItem subclass, the exact type depends on the
+ * action</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>toolitem</term>
+ * <listitem><para>a #GtkToolItem subclass, the exact type depends on the
+ * action. Note that toolitem elements may contain a menu element, but only
+ * if their associated action specifies a #GtkMenuToolButton as proxy.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>separator</term>
+ * <listitem><para>a #GtkSeparatorMenuItem or
+ * #GtkSeparatorToolItem</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>accelerator</term>
+ * <listitem><para>a keyboard accelerator</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * The "position" attribute determines where a constructed widget is positioned
+ * wrt. to its siblings in the partially constructed tree. If it is
+ * "top", the widget is prepended, otherwise it is appended.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="UI-Merging">
+ * <title>UI Merging</title>
+ * <para>
+ * The most remarkable feature of #GtkUIManager is that it can overlay a set
+ * of menuitems and toolitems over another one, and demerge them later.
+ *
+ * Merging is done based on the names of the XML elements. Each element is
+ * identified by a path which consists of the names of its anchestors, separated
+ * by slashes. For example, the menuitem named "Left" in the example above
+ * has the path <literal>/ui/menubar/JustifyMenu/Left</literal> and the
+ * toolitem with the same name has path
+ * <literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Accelerators</title>
+ * <para>
+ * Every action has an accelerator path. Accelerators are installed together with
+ * menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
+ * elements in the UI definition. This makes it possible to have accelerators for
+ * actions even if they have no visible proxies.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="Smart-Separators">
+ * <title>Smart Separators</title>
+ * <para>
+ * The separators created by #GtkUIManager are "smart", i.e. they do not show up
+ * in the UI unless they end up between two visible menu or tool items. Separators
+ * which are located at the very beginning or end of the menu or toolbar
+ * containing them, or multiple separators next to each other, are hidden. This
+ * is a useful feature, since the merging of UI elements from multiple sources
+ * can make it hard or impossible to determine in advance whether a separator
+ * will end up in such an unfortunate position.
+ *
+ * For separators in toolbars, you can set <literal>expand="true"</literal> to
+ * turn them from a small, visible separator to an expanding, invisible one.
+ * Toolitems following an expanding separator are effectively right-aligned.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Empty Menus</title>
+ * <para>
+ * Submenus pose similar problems to separators inconnection with merging. It is
+ * impossible to know in advance whether they will end up empty after merging.
+ * #GtkUIManager offers two ways to treat empty submenus:
+ * <itemizedlist>
+ * <listitem>
+ * <para>make them disappear by hiding the menu item they're attached to</para>
+ * </listitem>
+ * <listitem>
+ * <para>add an insensitive "Empty" item</para>
+ * </listitem>
+ * </itemizedlist>
+ * The behaviour is chosen based on the "hide_if_empty" property of the action
+ * to which the submenu is associated.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="GtkUIManager-BUILDER-UI">
+ * <title>GtkUIManager as GtkBuildable</title>
+ * <para>
+ * The GtkUIManager implementation of the GtkBuildable interface accepts
+ * GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
+ *
+ * A GtkUIManager UI definition as described above can be embedded in
+ * an GtkUIManager &lt;object&gt; element in a GtkBuilder UI definition.
+ *
+ * The widgets that are constructed by a GtkUIManager can be embedded in
+ * other parts of the constructed user interface with the help of the
+ * "constructor" attribute. See the example below.
+ *
+ * <example>
+ * <title>An embedded GtkUIManager UI definition</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkUIManager" id="uiman">
+ *   <child>
+ *     <object class="GtkActionGroup" id="actiongroup">
+ *       <child>
+ *         <object class="GtkAction" id="file">
+ *           <property name="label">_File</property>
+ *         </object>
+ *       </child>
+ *     </object>
+ *   </child>
+ *   <ui>
+ *     <menubar name="menubar1">
+ *       <menu action="file">
+ *       </menu>
+ *     </menubar>
+ *   </ui>
+ * </object>
+ * <object class="GtkWindow" id="main-window">
+ *   <child>
+ *     <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </para>
+ * </refsect2>
+ */
+
+
 #undef DEBUG_UI_MANAGER
 
 typedef enum
index 27cc84f5fc7f6693c49d58ebc6bc37410835e72b..8e8b618625dcb7782d2acb40965dac8ca75d28e9 100644 (file)
@@ -92,6 +92,24 @@ struct _GtkUIManagerClass {
   void (*_gtk_reserved4) (void);
 };
 
+/**
+ * GtkUIManagerItemType:
+ * @GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
+ * @GTK_UI_MANAGER_MENUBAR: Create a menubar.
+ * @GTK_UI_MANAGER_MENU: Create a menu.
+ * @GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
+ * @GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
+ * @GTK_UI_MANAGER_POPUP: Create a popup menu.
+ * @GTK_UI_MANAGER_MENUITEM: Create a menuitem.
+ * @GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
+ * @GTK_UI_MANAGER_SEPARATOR: Create a separator.
+ * @GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
+ * @GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the
+ *   actions' accelerators are shown.
+ *
+ * These enumeration values are used by gtk_ui_manager_add_ui() to determine
+ * what UI element to create.
+ */
 typedef enum {
   GTK_UI_MANAGER_AUTO              = 0,
   GTK_UI_MANAGER_MENUBAR           = 1 << 0,